Adding Panels to Dialog Boxes(IM:XP)

Inside Macintosh: QuickDraw GX Printing /: Chapter 3 - Page Formatting and Dialog Box Customization / Customizing QuickDraw GX Dialog Boxes

Adding Panels to Dialog Boxes
To add a panel to a dialog box, you call the GXInstallApplicationOverride function to override the messages that QuickDraw GX sends to display its dialog boxes. The following call to GXInstallApplicationOverride sets up the MyFormatDialogOverride function to be called when the application receives the gxFormatDialog message:
GXInstallApplicationOverride(myDocument->documentJob, 
                     gxFormatDialog, MyFormatDialogOverride);
The MyFormatDialogOverride function that is called in response to the message is as follows:
OSErr MyFormatDialogOverride(gxFormat aFormat, StringPtr title, 
                              gxDialogResult *result)
{
   OSErr    err = noErr;

   err = MySetUpByPagePanel(aFormat,GXGetMessageHandlerResFile());
   if (!err) err = Forward_FormatDialog(aFormat, title, result);
   return err;
}
Note
To remove the application override when a change to the default behavior associated with the message is no longer desired, use the GXInstallApplicationOverride function with the function pointer set to nil to take the override out of the message chain.
Because you have specified a function pointer in the GXInstallApplicationOverride function to override the message that displays the dialog box, QuickDraw GX calls the MyFormatDialogOverride function just before it displays the Custom Page Setup dialog box. The MyFormatDialogOverride function calls the GXSetupDialogPanel function for each panel that you want to add. The MyFormatDialogOverride function must forward the message to the next handler in the message chain.
Listing 3-22 shows the MySetUpByPagePanel function, which obtains information from the collection to set up a new panel, calls GXSetupDialogPanel, and forwards the message.
Listing 3-22 Setting up a new panel
#define kCreator                 'Ex#9'      /* registered 
                                                application 
                                                creator */
#define kMyKindaCollectionType   kCreator    /* collection 
                                                tag type */
#define r_MyFormatPanelResID     6000        /* ID of the panel 
                                                and panel icon 
                                                resources */

typedef struct MyKindaCollectionRec {
      unsigned char  isEnabled;              /* Enabled? */
      char           fillByte;               /* C adds this (if
                                                you don't) for 
                                                alignment */
} MyKindaCollectionRec, *MyKindaCollectionPtr, 
                                          **MyKindaCollectionHdl;

...

OSErr MySetUpByPagePanel(gxFormat aFormat, short ourResFile)
{
   OSErr                   err;
   Collection              fmtCollection;
   gxPanelSetupRecord      panelInfo;
   MyKindaCollectionRec    mySettings;

   /* 
      Access the format collection and search for the collection 
      object item in which the default settings are stored.
   */
   fmtCollection = GXGetFormatCollection(aFormat);

   err = GetCollectionItem(fmtCollection, kMyKindaCollectionType,
                           gxPrintingTagID, nil, &mySettings);

   /* 
      If the collection object item does not exist, create one and 
      add it to the format collection to support default settings 
      for the dialog panel.
   */
   if (err == collectionItemNotFoundErr)
   {
      mySettings.isEnabled = false;
      
      err = AddCollectionItem(fmtCollection, 
                              kMyKindaCollectionType,
                              gxPrintingTagID,
                              sizeof(MyKindaCollectionRec),
                              &mySettings);
   }

   /* 
      Install the panel. Specify its type, resource ID, and the 
      resource file in which it is located.
   */
   if (!err)
   {
      panelInfo.panelKind        = gxApplicationPanel;
      panelInfo.panelResId       = r_MyFormatPanelResID;
      panelInfo.resourceRefNum   = ourResFile;
      panelInfo.refCon           = 0;  /* not being used here */
      err = GXSetupDialogPanel(&panelInfo);
   }
   return err;
}
Once the user confirms or cancels the dialog box, QuickDraw GX disposes of all panel information. Note that while QuickDraw GX uses a resource file number supplied by the panel owner to look for panel resources, it does not leave the resource chain set to this file. The resource chain's current file is restored once the resources are retrieved.